⁄ V ! Ê ' fi ! , Y ! ã 0 0 7 u ! a ' k ! @ É 0 ‹ ' ! ^ Û 0 â ! ' 6 ! µ Õ 0 Ü ' ! ™ 0 √ Ò ! ≤ ! 0 ! ! ! !q ' !r ' !Ÿ ! "c #Ù ! $ÿ &M ! '? ! '@ ! 'A 8 'd < 'n )1 < )< 1⁄ 8 1ˆ ! 3 ! 4x ! 4é H 4ù ! 6e ! ≥ à à ® L
‰
à ¬ π
≤
π
ï Ó «
| Ó « ˚
ã ì
∂ „
˚
˛ €
œ ®
° ·
∏ Ã
É Ò
Ó Ù
g V
# √ $ ⁄
% ‰ $ ˇ
% · $ À
% $ $
% π $ Æ
% Ê à fi
# â $ æ
% $
% o $ s
% é $ ò
% $
% $
% , Y
# z $ ∞
% ª $ »
% ã õ - ÷ . ( 0 2 7 u
# y $
% ⁄ $ ¢
% æ $ ë
% $
% a à j
) k
# y $ }
% ° $ º
% ¿ $ Ë
% @ É 2 ‹ à
)
# $ )
% Q $ Y
% ^ Û 2 â ! à 5
) 6
# : $ ?
% µ Õ 2 Ü à
)
# " $ '
% ⁄ $
% ™ 2 √ Ò
# Õ $ à
% õ $ ü
% 8 $ @
% ≤
# Ù $ á
% 2 $ :
% o $ y
% Ÿ $
% ¬ $ ´
% Å $ Ê
% n $ v
% Í $ ß
% ! $ !
% !$ $ !'
% !_ $ !g
% !q à !‘
) !Ÿ
# !Œ $ !˜
% "! $ "'
% "- $ "6
% "Q $ "Z
% "c "x - "y
"Ω . "—
"ª #Ù
# #† $ #è
% #í $ #ø
% $( $ $3
% $E $ $K
% $x $ $∞
% $ $ $ƒ
% $¸ $ $¿
% $ÿ &M
# 'A Ó ª 'c : 'd > 'n )1 > )< )N - )P . )• 0, - 0. . 0_ 1⁄ Ó ª 1 : 1ˆ
# 4é à – 4ø J 4ù
# ‘ û˚18 û ˜dt û‡˚¨ô øú˚3x òÿ˚3t ñÏ˚ªø Àù˚ªô ’é˚84 ¢ú˚« #˛ú˚«( 'ˆê˚«$ +•ñ˚«< /q˚ªì 2•æ˚ªä û
›
T E C H N O T E :
Printer Direct Mode APIs
for Macintosh Printer Drivers
By Mike Blackstock, GDT Softworks, Inc. & Ben Manuto, Apple Engineering
mike_blackstock@gdt.com
This Technote describes the APIs for implementing a printer-direct (or pass-thru) mode for Macintosh printer drivers. Implementing this feature will allow applications to identify and send printer data that is unique to the printer connected to the Macintosh without having to generate QuickDraw codes, understand how to connect to and maintain a connection with a particular printer, or handle communications errors with the printer.
AppleÕs PC Compatibility systems present an interesting dilemma when trying to print from the DOS/Windows side of the CPU because all of the I/O of this system must occur through the Macintosh. DOS applications and Windows printer drivers generate native printer codes for specific printers, but do not generate the QuickDraw commands that Macintosh printer drivers depend on in order to image data to a specific printer. This printer direct mode will allow a Òback-doorÓ for these native printer commands to get directly to the printer through the Macintosh printer driver.
This Technote is directed towards printer driver developers who write drivers for non-PostScript printers. Implementing this feature will allow faster and better quality printing with AppleÕs PC Compatibility products, where printing must always occur on the Macintosh, even though the printer driver generating the printer commands may be on a DOS/Windows system.
This document assumes you are familiar with the Macintosh Printing Manager and AppleÕs PC Compatibility products. See Inside Macintosh:Imaging with QuickDraw for further details on the Printing Manager.
About the Printer Direct Mode
The printer direct (or pass-thru) mode is specifically intended to allow printer manufacturers and printer driver developers to make products that will easily integrate into the PC Compatibility CPU marketplace. Since most new printers ar ‡e not being developed for a single CPU platform, the printer direct mode will give end-users the best printing results possible.
Using the Printer Direct APIs
The printer direct printer driver functions are implemented via a set of PrGeneral routines and a reserved opCode for those routines. There is a set of six functions (for which there are selectors) that the Macintosh printer driver must support:Open, Close, SendData, SendFile, Despool, and Verify. The PrGeneral opCode reserved by Apple for this operation is 20 decimal ($14 hex). Each of the five functions take a selector code as defined by these constants:
#define kPrinterDirectOpCode 20
#define kPDOpenSelect 1
#define kPDSendDataSelect 2
#define kPDSendFileSelect 5
#define kPDCloseSelect 3
#define kPDDespoolSelect 4
#define kPDVerifySelect 6
If the driver does not support the printer direct opCode, the PrGeneral function should return a opNotImpl error. This is the one case where an error code will on úly be returned in the printer error (PrError). For all the rest of the functions, error codes need to be returned in the error field of the parameter block as well as the printing error variable (PrSetError).
Open Printer Direct
The Open command alerts the printer driver that data is about to be sent and it should allocate whatever memory structures are needed to begin receiving the printer data. This printer data can be passed to the driver in one of two ways: 1) As a pointer to data blocks of a specific size, or 2) an FSSpec record which points to a spool file where the data is located. The appropriate selector code for Open command and an appropriate selector for the type of data to be sent to the driver must entered into the selector and spoolType fields of the OpenPDBlk. The spoolType valid values are:
#define kPDData 1
#define kPDFileSpec 2
If any other value is set in the spoolType field, the function should return the pdBadSpoolTypeErr. The format of the parameter block is:
The opCode is always 20 (kPrinterDirectOpCode). The error and reserved fields should be initialized to zero. The jobID is returned from the Open function and it is the calling functionÕs unique identifier to the print job being opened.
Send Data
There are two Send commands for sending the print job to the printer:SendPDData and SendFileSpec. For sending data, the driver must minimally be able to handle 4K data blocks which are repeatedly sent to the printer until all the data has been sent. However, more data can be sent if the driver can handle additional memory requirements. If the driver is not able to handle any data block l Ïarger than 4K, an error must be appropriately returned by the printer driver.
The Send File command is issued once and specifies a fileSpec for the location of the spooler file containing all of the print job data. This file must be in a closed state when it is passed to the driver. The printer driver is responsible for deleting the spool file when it is finished spooling the file to the printer.
Once the Close command is completed, the printer driver will only dispatch the printer data once it has received the Despool command. Despooling can take place éeither in the foreground or the background, depending on the userÕs selection in the Chooser.
An idleProcPtr can be supplied for Despool function which the driver should execute periodically. The idleProc should be a function which takes no arguments and returns no values and should be of the form:
pascal void MyIdleProc(void);
The primary purpose of the idleProc is to sense events when a user is attempting to abort the print job. Should the idleProc sense this, it must set the printing error (via the PrSetError function) with the iPrAbort error. Other úwise, the idleProc should return a noErr. The driver should check the error returned and abort the print job upon receiving the abort error.
Should the despool procedure be aborted, it should return the iPrAbort error. If the despool function should fail for any other reason, it should return the pdDespoolFailedErr so the calling application can prompt the user.
If the idleProc is nil, it is the printer driverÕs option to supply a default idleProc routine.
Verify Printer Direct Mode
The Verify function allows an application to verify that the driver supports printer direct mode. If the driver does not support the printer direct opCode, the PrGeneral function should return an opNotImpl error.
struct VerifyPDBlk {
SInt16 opCode; // Printer Direct opCode = 20
OSErr error; // Result code
UInt32 reserved; // reserved
UInt32 selector; // Function selector code
OSType drvrCreator; // Printer driverÕs creator type
NumVersion drvrVersion; // Printer driverÕs version number ú
The drvrCreator and drvrVersion fields are returned by the printer driver. The drvrCreator is a 4 character OSType that is part of the driverÕs file info. The drvrVersion field is of type NumVersion which is defined in the Types.h file of the Macintosh headers. It is defined there as follows:
struct NumVersion {
UInt8 majorRev; /*1st part of version number in BCD*/
UInt8 minorAndBugRev; /*2nd & 3rd part of version number
UInt8 nonRelRev; /*revision level of non-released version*/
};
typedef struct NumVersion NumVersion;
Based on the creator and version information, and any pertinent information in the printer record, it is up to the calling application to determine whether the printer data being sent to this driver would be handled properly by this printer.
The printer-direct mode for Macintosh printer drivers described in this Technote will be used by the PC Print Spooler application, which is part of AppleÕs new PC Compatibility System and should be relased in the first part of 1996. T æhe PC Print Spooler application spools print jobs from the PC side of the CPU to the printer connected to the Macintosh and selected in the Chooser.
The printer-direct mode will be implemented in PowerPrint 3.0.1 Classic and LT driver packages from GDT Softworks in February, 1996. This feature is also being considered in a future release of AppleÕs LaserWriter 8 driver. In addition, other third-party providers have shown interest in implementing this feature in their printer drivers in the future.
A caveat:Application developers should realize that this feature is currently not supported by AppleÕs drivers.
Acknowledgments
Thanks to Ingrid Kelly, Guillermo Ortiz, and Dave Polaschek for reviewing this Technote. Special thanks to Tom Dowdy for reviewing the design and helping us think about the future compatibility. We would also like to thank Greg Manning, Gord Pawluik, Pierre Houston, and Dave Banks from GDT Softworks for their help in reviewing and contributing to this Technote.
Z ÿÿ N õ DSET ≠ ÿÿ . H ÿÿÿÿÿÿ˚50 õ › b ¯ • õ ÿÿ 6 ÿÿ * b ¯ DSET 4 ÿÿ . H ∂g ltÿÿÿÿÿÿ˚¨ ¯ · õ ÿÿ › § õ ÿÿ à ˜ õ ÿÿ ‹ Ω õ ÿÿ À w õ ÿÿ ° g õ ÿÿ W õ ÿÿ Δ G õ ÿÿ ¸ › õ ÿÿ ¨ à õ ÿÿ ˘ ‹ õ ÿÿ √ À õ ÿÿ x ° õ ÿÿ h õ ÿÿ X Δ õ ÿÿ H • õ ÿÿ 6 ÿÿ * b ¯ DSET ≠ ÿÿ . H @ ÿÿÿÿÿÿ˚«0 ?• I 8 õ ÿÿ ∫ ÿÿ * ?• I õ 8 √ õ 8 √ õ 8
ÿÿ 7 E F0 = @ ÿÿ 8 F G0 = @ ÿÿÿÿ G I0 = ? $ ÿÿÿÿ H K0 = ? % ÿÿÿÿ I L0 = A & ÿÿ < J M0 = A ÿÿÿÿ % K N‹ ÿÿÿÿ ÿÿ L O0 N N ' ÿÿÿÿ M P0 N N ( ÿÿÿÿ N Q0 N N ( ÿÿÿÿ O R0 N P ) ÿÿÿÿ P S0 N P * ÿÿÿÿ Q T0 N P * ÿÿÿÿ R U0 N P *
ÿÿÿÿ S V0 N P * ÿÿÿÿ T W0 N P * ÿÿÿÿ U X0 N O + ÿÿÿÿ V Y0 N O + ÿÿÿÿ W Z0 N Q ) ÿÿÿÿ X [0 N Q * ÿÿÿÿ % Y \‹ ÿÿÿÿ ÿÿ Z ]0 \ \ , ÿÿÿÿ [ ^0 \ \ ÿÿÿÿ \ _0 \ \ ÿÿÿÿ ] `0 \ ^ - ÿÿÿÿ ^ a0 \ ^ ÿÿÿÿ _ b0 \ ^ ÿÿÿÿ ` c0 \ ^ ! ÿÿÿÿ a d0 \ ^ " ÿÿÿÿ b e0 \ ^ # ÿÿÿÿ c f0 \ ] . $
ÿÿÿÿ d g0 \ ] . %
ÿÿÿÿ e h0 \ _ & ÿÿÿÿ f i0 \ _ ' ÿÿÿÿ % g j‹ ÿÿÿÿ ( ÿÿ h k0 j j / ) ÿÿÿÿ i l0 j j * ÿÿÿÿ j m0 j j + ÿÿÿÿ k n0 j l , ÿÿÿÿ l o0 j l - ÿÿÿÿ m p0 j l . ÿÿÿÿ n q0 j l / ÿÿÿÿ o r0 j l 0 ÿÿÿÿ p s0 j l 1 ÿÿÿÿ q t0 j k 0 6
ÿÿÿÿ r u0 j k 0 7
ÿÿÿÿ s v0 j m & 4
ÿÿÿÿ t w0 j m 5
ÿÿÿÿ u x‹ ÿÿÿÿ ( ÿÿ v y0 x x ) ÿÿ i w z0 x x * ÿÿÿÿ x {0 x x 2 ÿÿÿÿ y |0 x z , ÿÿÿÿ z }0 x z 3 ÿÿÿÿ { ~0 x z 8 ÿÿÿÿ | 0 x z 9 ÿÿÿÿ } •0 x z : ÿÿÿÿ ~ ™0 x y 1 6
